<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>The Dispatcher - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.controller.dispatcher.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.controller.dispatcher.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.controller.router.html">The Standard Router</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.controller.html">Zend_Controller</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.controller.action.html">Action Controllers</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.controller.dispatcher" class="section"><div class="info"><h1 class="title">The Dispatcher</h1></div>
    

    <div class="section" id="zend.controller.dispatcher.overview"><div class="info"><h1 class="title">Overview</h1></div>
        

        <p class="para">
            Dispatching is the process of taking the request object,
            <span class="classname">Zend_Controller_Request_Abstract</span>, extracting the module
            name, controller name, action name, and optional parameters
            contained in it, and then instantiating a controller and calling an
            action of that controller. If any of the module, controller, or
            action are not found, it will use default values for them.
            <span class="classname">Zend_Controller_Dispatcher_Standard</span> specifies
            <em class="emphasis">index</em> for each of the controller and action defaults
            and <em class="emphasis">default</em> for the module default value, but allows
            the developer to change the default values for each using the
             <span class="methodname">setDefaultController()</span>,
             <span class="methodname">setDefaultAction()</span>, and
             <span class="methodname">setDefaultModule()</span> methods, respectively.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Default Module</b><br /></span>
            

            <p class="para">
                When creating modular applications, you may find that you want
                your default module namespaced as well (the default
                configuration is that the default module is
                <em class="emphasis">not</em> namespaced). As of 1.5.0, you can now
                do so by specifying the <span class="property">prefixDefaultModule</span> as
                <b><tt>TRUE</tt></b> in either the front controller or your dispatcher:
            </p>

            <pre class="programlisting brush: php">
// In your front controller:
$front-&gt;setParam(&#039;prefixDefaultModule&#039;, true);

// In your dispatcher:
$dispatcher-&gt;setParam(&#039;prefixDefaultModule&#039;, true);
</pre>


            <p class="para">
                This allows you to re-purpose an existing module to be the
                default module for an application.
            </p>
        </p></blockquote>

        <p class="para">
            Dispatching happens in a loop in the front controller. Before
            dispatching occurs, the front controller routes the request to find
            user specified values for the module, controller, action, and optional
            parameters. It then enters a dispatch loop, dispatching the request.
        </p>

        <p class="para">
            At the beginning of each iteration, it sets a flag in the request
            object indicating that the action has been dispatched. If an action
            or pre or postDispatch plugin resets that flag, the dispatch loop will
            continue and attempt to dispatch the new request. By changing the
            controller and/or action in the request and resetting the dispatched
            flag, the developer may define a chain of requests to perform.
        </p>

        <p class="para">
            The action controller method that controls such dispatching is
             <span class="methodname">_forward()</span>; call this method from any of the
             <span class="methodname">preDispatch()</span>,  <span class="methodname">postDispatch()</span> or
            action methods, providing an action, controller,
            module, and optionally any additional parameters you may wish to
            send to the new action:
        </p>

        <pre class="programlisting brush: php">
public function fooAction()
{
    // forward to another action in the current controller and module:
    $this-&gt;_forward(&#039;bar&#039;, null, null, array(&#039;baz&#039; =&gt; &#039;bogus&#039;));
}

public function barAction()
{
    // forward to an action in another controller:
    // FooController::bazAction(),
    // in the current module:
    $this-&gt;_forward(&#039;baz&#039;, &#039;foo&#039;, null, array(&#039;baz&#039; =&gt; &#039;bogus&#039;));
}

public function bazAction()
{
    // forward to an action in another controller in another module,
    // Foo_BarController::bazAction():
    $this-&gt;_forward(&#039;baz&#039;, &#039;bar&#039;, &#039;foo&#039;, array(&#039;baz&#039; =&gt; &#039;bogus&#039;));
}
</pre>

    </div>

    <div class="section" id="zend.controller.dispatcher.subclassing"><div class="info"><h1 class="title">Subclassing the Dispatcher</h1></div>
        

        <p class="para">
            <span class="classname">Zend_Controller_Front</span> will first call the router to
            determine the first action in the request. It then enters a dispatch
            loop, which calls on the dispatcher to dispatch the action.
        </p>

        <p class="para">
            The dispatcher needs a variety of data in order to do its work - it
            needs to know how to format controller and action names, where to
            look for controller class files, whether or not a provided module
            name is valid, and an <acronym class="acronym">API</acronym> for determining if a given request is even
            dispatchable based on the other information available.
        </p>

        <p class="para">
            <span class="classname">Zend_Controller_Dispatcher_Interface</span> defines the
            following methods as required for any dispatcher implementation:
        </p>

        <pre class="programlisting brush: php">
interface Zend_Controller_Dispatcher_Interface
{
    /**
     * Format a string into a controller class name.
     *
     * @param string $unformatted
     * @return string
     */
    public function formatControllerName($unformatted);

    /**
     * Format a string into an action method name.
     *
     * @param string $unformatted
     * @return string
     */
    public function formatActionName($unformatted);

    /**
     * Determine if a request is dispatchable
     *
     * @param  Zend_Controller_Request_Abstract $request
     * @return boolean
     */
    public function isDispatchable(
        Zend_Controller_Request_Abstract $request
    );

    /**
     * Set a user parameter (via front controller, or for local use)
     *
     * @param string $name
     * @param mixed $value
     * @return Zend_Controller_Dispatcher_Interface
     */
    public function setParam($name, $value);

    /**
     * Set an array of user parameters
     *
     * @param array $params
     * @return Zend_Controller_Dispatcher_Interface
     */
    public function setParams(array $params);

    /**
     * Retrieve a single user parameter
     *
     * @param string $name
     * @return mixed
     */
    public function getParam($name);

    /**
     * Retrieve all user parameters
     *
     * @return array
     */
    public function getParams();

    /**
     * Clear the user parameter stack, or a single user parameter
     *
     * @param null|string|array single key or array of keys for
     *        params to clear
     * @return Zend_Controller_Dispatcher_Interface
     */
    public function clearParams($name = null);

    /**
     * Set the response object to use, if any
     *
     * @param Zend_Controller_Response_Abstract|null $response
     * @return void
     */
    public function setResponse(
        Zend_Controller_Response_Abstract $response = null
    );

    /**
     * Retrieve the response object, if any
     *
     * @return Zend_Controller_Response_Abstract|null
     */
    public function getResponse();

    /**
     * Add a controller directory to the controller directory stack
     *
     * @param string $path
     * @param string $args
     * @return Zend_Controller_Dispatcher_Interface
     */
    public function addControllerDirectory($path, $args = null);

    /**
     * Set the directory (or directories) where controller files are
     * stored
     *
     * @param string|array $dir
     * @return Zend_Controller_Dispatcher_Interface
     */
    public function setControllerDirectory($path);

    /**
     * Return the currently set directory(ies) for controller file
     * lookup
     *
     * @return array
     */
    public function getControllerDirectory();

    /**
     * Dispatch a request to a (module/)controller/action.
     *
     * @param  Zend_Controller_Request_Abstract $request
     * @param  Zend_Controller_Response_Abstract $response
     * @return Zend_Controller_Request_Abstract|boolean
     */
    public function dispatch(
        Zend_Controller_Request_Abstract $request,
        Zend_Controller_Response_Abstract $response
    );

    /**
     * Whether or not a given module is valid
     *
     * @param string $module
     * @return boolean
     */
    public function isValidModule($module);

    /**
     * Retrieve the default module name
     *
     * @return string
     */
    public function getDefaultModule();

    /**
     * Retrieve the default controller name
     *
     * @return string
     */
    public function getDefaultControllerName();

    /**
     * Retrieve the default action
     *
     * @return string
     */
    public function getDefaultAction();
}
</pre>


        <p class="para">
            In most cases, however, you should simply extend the abstract class
            <span class="classname">Zend_Controller_Dispatcher_Abstract</span>, in which each of
            these have already been defined, or
            <span class="classname">Zend_Controller_Dispatcher_Standard</span> to modify
            functionality of the standard dispatcher.
        </p>

        <p class="para">
            Possible reasons to subclass the dispatcher include a desire to
            use a different class or method naming schema in your action
            controllers, or a desire to use a different dispatching paradigm
            such as dispatching to action files under controller directories
            (instead of dispatching to class methods).
        </p>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.controller.router.html">The Standard Router</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.controller.html">Zend_Controller</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.controller.action.html">Action Controllers</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="reference.html">Refer&ecirc;ncia do Zend Framework</a></li>
  <li class="header up"><a href="zend.controller.html">Zend_Controller</a></li>
  <li><a href="zend.controller.quickstart.html">Guia de In&iacute;cio R&aacute;pido do Zend_Controller</a></li>
  <li><a href="zend.controller.basics.html">O B&aacute;sico de Zend_Controller</a></li>
  <li><a href="zend.controller.front.html">The Front Controller</a></li>
  <li><a href="zend.controller.request.html">The Request Object</a></li>
  <li><a href="zend.controller.router.html">The Standard Router</a></li>
  <li class="active"><a href="zend.controller.dispatcher.html">The Dispatcher</a></li>
  <li><a href="zend.controller.action.html">Action Controllers</a></li>
  <li><a href="zend.controller.actionhelpers.html">Action Helpers</a></li>
  <li><a href="zend.controller.response.html">The Response Object</a></li>
  <li><a href="zend.controller.plugins.html">Plugins</a></li>
  <li><a href="zend.controller.modular.html">Using a Conventional Modular Directory Structure</a></li>
  <li><a href="zend.controller.exceptions.html">MVC Exceptions</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>